home *** CD-ROM | disk | FTP | other *** search
/ Archive Magazine CD 1995 / Archive Magazine CD 1995.iso / discs / prog_disc / volume_8 / issue_06 / risc_os / Wimp / IconBar < prev    next >
Encoding:
Text File  |  1988-12-06  |  4.5 KB  |  115 lines
  1. > Wimp.IconBar
  2.  
  3. New Calls
  4. ---------
  5.  
  6.         Wimp_CreateIcon
  7.         Wimp_DeleteIcon
  8.         Wimp_SetIconState
  9.         Wimp_GetIconState
  10.         Wimp_Poll: reason code 6 (Mouse_Click) is returned to the icon owner
  11.  
  12.  
  13. Overview
  14. --------
  15.  
  16. The window manager provides an iconbar facility to allow tasks to register
  17. icons in a central place.
  18.  
  19. The iconbar appears as a thick bar at the bottom of the screen, containing
  20. filing system icons on the left, and 'utility' icons on the right (note that
  21. the iconbar is only displayed when there are icons in it).
  22.  
  23. When the mouse is clicked on one of the icons, the Wimp returns the
  24. mouse_click event to the task which registered the icon originally.
  25.  
  26. If there are so many icons on the icon bar that it fills up, the Wimp will
  27. automatically scroll the bar whenever the mouse pointer is moved close to
  28. either end of the bar.
  29.  
  30.  
  31. Interface
  32. ---------
  33.  
  34. The following SWIs recognise funny window handles on input:
  35.  
  36.     -1 = iconbar (utilities)
  37.     -2 = iconbar (filing systems)
  38.  
  39. Wimp_CreateIcon                 ; can cause other icons to shuffle
  40. Wimp_DeleteIcon                 ; can cause other icons to shuffle
  41. Wimp_SetIconState
  42. Wimp_GetIconState 
  43.  
  44. Wimp_GetPointerInfo                     ; these two return identical blocks:
  45. Wimp_Poll: reason code 6 (Mouse_Click)  ;
  46.  
  47. Exit:  R1 --> block
  48.           +0 = mouse x
  49.           +4 = mouse y
  50.           +8 = buttons          ; icon's button type determines format
  51.          +12 = -2               ; icon bar window handle (NB -1 ==> background)
  52.          +16 = icon handle      ; as returned from Wimp_CreateIcon
  53.  
  54. NB: SetIconState can be used to cause an icon to be updated (use indirected
  55.     icon if (eg) sprite name is to be changed.  Note that the icon size
  56.     cannot be changed (that would cause the other icons to move).
  57.  
  58.  
  59. Dimensions of iconbar
  60. ---------------------
  61.  
  62. When CreateIcon is called to put an icon on the bar, the Wimp only uses the x
  63. coordinates of the icon to determine its width, and then positions the icon
  64. as it sees fit.  However, for reasons of flexibility, it does not vertically
  65. centre the icon, but actually uses both the y-coordinates given to determine
  66. the icons position.  This means that applications must be aware of the
  67. 'standard' dimensions of the bar, in order to positions its icons correctly.
  68.  
  69. There are two main types of icon which are put onto the icon bar:  those
  70. consisiting simply of a sprite, and those consisting of a sprite with text
  71. written underneath (see Wimp.Icons for details).  The diagram below
  72. summarises the rules governing the positioning of such icons:
  73.  
  74. top     92 +---------------------------------------+ 92
  75.            !   <---c.64----><-24-->                !
  76.            !                       +-----------+   ! 84 (max)
  77.         68 !   +-----------+       !           !   !
  78.            !   !           !       !           !   !
  79.            !   !  sprite   !       !  sprite   !   !       The actual iconbar
  80.            !   !   only    !       !           !   !       stretches right
  81.            !   !           !       !           !   !       across the screen.
  82.            !   !           !       +-----------+   ! 20
  83.            !   !           !       +-----------+   ! 16
  84.          0 !   +-----------+       !  text     !   !
  85.            !                       +-----------+   ! -16
  86.            !                                       !
  87. bottom -24 +---------------------------------------+ -24
  88.  
  89. Note that there are two 'baseline' positions: one for sprites with text
  90. underneath, and one for those without.  The overall effect is better if most
  91. of the sprites are of a similar size, since otherwise there is a conflict
  92. between wanting the sprites to line up on the baseline, and wanting to
  93. vertically-centre them.
  94.  
  95. The general rule is that sprites with text underneath them should always be
  96. positioned on the baseline (y=20), whereas sprites without text can safely be
  97. vertically-centred (although if they are close to 68 OS units high, it is
  98. better to put them on their baseline (y=0).
  99.  
  100.  
  101. Guidance for Application software
  102. ---------------------------------
  103.  
  104. Either: arrange it so that the application always has at least one window
  105.         present (eg. Text editor would close down when all text windows have
  106.         been closed).
  107. Or:     register an icon on the icon bar
  108.         this is primarily for resident utilities (eg. clock / calculator)
  109.  
  110. Multi-tasking applications should never put immoveable windows on the
  111. desktop, so that the iconbar cannot be obscured.  Note that old-style
  112. Wimp_Init applications cause everything else to be obscured anyway, so they
  113. are OK.
  114.  
  115.